…ev#9869)

Adds product.md + tech.md for issue warpdotdev#9869: the voice input hotkey
picker in Settings > Agents > Voice exposes a fixed list of 10
modifier/function keys, missing Caps Lock and individual F-keys
(F1-F12) — the two most-requested options for push-to-talk in real
ergonomic setups — and offering no escape hatch for any other key.

Investigation:
- Setting is VoiceInputToggleKey enum at app/src/settings/ai.rs:110.
  Closed enum with hand-written display_name, to_key_code, keystroke,
  and tooltip_message methods.
- Underlying KeyCode at crates/warpui_core/src/platform/keyboard.rs
  already supports CapsLock and F1-F35; the enum is artificially
  narrower than the platform layer can handle.
- Persistence is SyncToCloud::Never (intentional, per-device
  keyboards) — preserved.
- Action dispatch at block_list_element.rs:3072 and
  alt_screen_element.rs:620 already speaks KeyCode, so new variants
  don't require dispatch-layer changes.

Spec proposes:
- Extend the enum with CapsLock, F1-F12, and a Custom(KeyCode)
  variant (single source of truth, justified against an
  override-field alternative).
- Sectioned dropdown ("Modifier keys" / "Function keys" / "Other")
  to keep 22 entries scannable; existing modifiers stay at the top
  so existing users see no reorder.
- Press-to-capture modal for "Custom key..." with a B5 reject-list
  (app-quit shortcut, Enter/Escape/Tab/Backspace/Space) and an
  >800ms held-modifier carve-out.
- Caps Lock on macOS uses press-to-toggle semantics (one tap on,
  next tap off) because macOS Caps Lock fires only on toggle
  events, not press/release. Discord and Krisp both take this
  approach.
- Validation reset for hand-edited TOML with unbindable values,
  with a one-time toast.

Test plan covers ten unit cases (TOML round-trip, display, key
mapping, toggle-mode, validation reset) and three integration
tests (modal capture flow, Caps Lock toggle, F-key hold-to-talk).

Four open questions for maintainer review on SettingsValue derive
support for payload variants, dropdown section heading
constructors, the macOS Caps Lock decision, and KeyCode display
exposure.

Bot review (warpdotdev#10127) identified 1 critical + 4 important + 1 security
suggestion concerns:

- Critical: product and tech specs disagreed on whether macOS Caps
  Lock is hold-to-talk or tap-to-toggle.
- Important: Custom(KeyCode) breaks the existing EnumIter /
  all_possible_values() flow with no concrete replacement.
- Important: TOML format for Custom variant was specified two ways
  (`{ kind = "custom", key = "f19" }` and `{ custom = "F19" }`).
- Important: app-quit reject-list compared bare KeyCode, not
  Keystroke — would either ban bare Q or fail to reject Cmd+Q.
- Important: validation hook can never see TOML values that fail
  parsing, so A6's toast would never fire.
- Suggestion: telemetry must explicitly exclude raw capture
  attempts and rejected/cancelled keypresses.

Fixes:

- B1 split into platform-specific semantics: macOS press-to-toggle
  (one tap on, next tap off — matches macOS Caps Lock event model
  and Discord/Krisp UX), Windows/Linux hold-to-talk. A4 acceptance
  criterion split into A4-mac and A4-win-lin.
- Added "Replacing the EnumIter / all_possible_values() flow"
  section with a concrete predefined_options() function that returns
  the curated unit variants only. Custom(KeyCode) is constructed at
  capture time, not iterated. EnumIter derive is dropped.
- Added "Settings serialization" section justifying the hand-written
  Serialize/Deserialize impl over a one-off macro extension.
- Canonicalized the TOML format to `{ custom = "f19" }` with
  KeyCode payload as snake_case lowercased Serde-default. Tests
  assert exact strings.
- Reject-list comparison now uses full Keystroke (key + modifiers)
  for app-quit and the existing voice-input shortcut. Static
  structural rejects (Enter/Escape/Tab/Backspace/Space) remain
  bare-key. The bare-modifier rule is preserved via the >800ms held-
  modifier carve-out.
- Settings-reset (A6) split into two paths: raw parse failure
  (intercepted in the hand-written Deserialize impl, surfaced via a
  side-channel Mutex<Option<String>>) and parsed-but-unbindable
  (post-parse validate() check). Both fire the same toast.
- Added explicit telemetry privacy guardrails to B8: only the final
  saved value is emitted, never raw captures, rejected keys, or
  cancelled captures; respects global opt-out.

Each correction includes a "Correction (review warpdotdev#10127)" callout so
reviewers can cross-reference the bot's concerns.

Round-2 bot review identified 4 remaining concerns:

- A4 acceptance criterion still required hold/release semantics
  for every bound key, contradicting B1's macOS Caps Lock tap-to-
  toggle that I added in round 1.
- The reject-list rule for the currently-bound voice-input
  shortcut would have prevented users from changing their existing
  custom hotkey — the literal opposite of the modal's purpose.
- Path 1 of the A6 reset flow proposed mutating a side-channel
  Mutex on the containing AISettings struct from inside the field
  Deserialize impl. That isn't feasible Serde — a field
  deserializer doesn't have a reference to its container.
- Product and tech specs still disagreed on whether invalid TOML
  is left unchanged or rewritten.

Fixes:

- A4 split into A4-win-lin (hold-to-talk) and A4-mac (Caps Lock
  tap-to-toggle, all other keys hold-to-talk). The split mirrors
  B1's existing platform breakdown.
- Reject-list: removed the "reject voice-input self-conflict"
  rule. Same-key re-confirm is handled by accepting the capture
  and short-circuiting the dispatch when the captured KeyCode
  equals the current one. The dispatch handler at
  block_list_element.rs:3072 only fires voice activation, never
  re-binds, so there is no infinite-loop risk.
- A6 reset path rewritten with a feasible Serde design: the
  storage type is a #[serde(untagged)] wrapper enum
  VoiceInputTomlValue { Valid(VoiceInputToggleKey),
  Invalid(toml::Value) } that captures both successful and failed
  parses without erroring out. A single post-init pass on
  AISettings::initialize drains the Invalid branch, logs, rewrites
  the TOML on disk, and fires the toast. No side-channel mutation
  from inside a deserializer.
- Path 2 (parsed-but-unbindable) folded into the same routine,
  guaranteeing A6's toast fires once for any combination of TOML-
  parse-failure and post-parse-validation-failure.
- product.md A6 updated to "TOML is rewritten" so it matches
  tech.md.

Each correction includes a "Correction (re-review warpdotdev#10127)" callout.

…ec (round 3)

Round-3 bot review identified 2 important + 1 suggestion:

- Product B5 still listed "the currently-bound voice-input
  shortcut itself" as a reject-list entry, contradicting the
  tech-spec round-2 fix that removed it (it would have prevented
  users from changing an existing custom hotkey).
- Tech spec did not specify how the dropdown displays the
  *currently selected* value when that value is a Custom(KeyCode)
  outside predefined_options(). Without spec, the
  set_selected_by_index(None) path would silently fall back to
  index 0 — a data-loss bug.
- Modal display open question still unresolved (whether to show
  protocol-level KeyCode spelling).

Fixes:

- B5 product reject-list updated to drop the voice-input self-
  conflict entry, matching tech.md round 2.
- Added "Displaying a persisted Custom(KeyCode) in the dropdown"
  section: virtual "Custom: <friendly-name>" row prepended when
  the current value is a Custom not in predefined_options();
  re-opens the modal pre-populated when clicked. No data loss on
  render.
- Resolved open question 4: friendly display name primary,
  protocol-level KeyCode in hover tooltip only. Same friendly
  name on dropdown row and modal display.

Each correction includes a "Correction (re-review warpdotdev#10127)" callout.

- Modal body display reconciled: friendly name only, KeyCode in
  hover tooltip. Earlier draft had inline KeyCode spelling that
  contradicted the round-3 Open Question 4 resolution.
- Open Question 1 (SettingsValue derive macro) closed: committed
  to manual Serialize/Deserialize impl per round-2 Settings
  serialization section. Open Question 4 was already closed.
- VoiceInputTomlValue wrapper API reconciled: wrapper is an
  internal implementation detail. All external accessors
  (set_value, value(), tests, dropdown reads, dispatch) continue
  to see the unwrapped VoiceInputToggleKey. After post-init the
  field is always Valid(...), with the unwrap happening in the
  accessor. Tests don't see the wrapper.